home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 5 / Apprentice-Release5.iso / Source Code / C++ / Applications / PICSee Dust 1.01 / Quaternary Source / Class_DynamoArray.h < prev    next >
Text File  |  1995-11-23  |  7KB  |  223 lines
  1. #ifndef CLASS_DYNAMOARRAY_H_
  2. #define CLASS_DYNAMOARRAY_H_
  3.  
  4. /*
  5.     Class_DynamoArray.h
  6.  
  7.     Version 2.0
  8.     (c)1993, 1994, 1995 by Hiep Dam. All Rights Reserved.
  9.     From The Witches' Brew
  10.  
  11.     ---------------------------------------------------------------------------
  12.  
  13.     "Dynamic" arrays implemented as a C++ template class. Pretty self-explanatory.
  14.  
  15.     Reason for this class? Well, I needed to maintain a dynamic list of items
  16.     that were to be randomly chosen, one item at a time. However, once that
  17.     item was chosen, it was NOT to be chosen again. The best way to do
  18.     this was via a dynamic array: getting the item and then deleting it from
  19.     the array and then shrinking the array by 1.
  20.  
  21.     Note however that in the implementation I don't actually "shrink" the array;
  22.     I just decrement the array size counter. The array is allocated via _new.
  23.     You might change this implementation if you have large arrays and memory
  24.     usage is critical for you.
  25.  
  26.     This is also a good sample to work from if you're new to C++ and OOP.
  27.  
  28.     ---------------------------------------------------------------------------
  29.  
  30.     Created: December 21, 1993.
  31.         Just for your information, I spent 5 hours one night developing this
  32.         class (from midnight to 5 in the morning. I must be crazy).
  33.  
  34.     Version History:
  35.         12/24/93
  36.             Added [] operator and fixed minor bug in destructor.
  37.  
  38.         4/1/94
  39.              Added copy constructor, assignment constructor
  40.  
  41.         4/21/95
  42.              Updated copy constructor so it would
  43.              delete old array after copying...
  44.  
  45.         4/22/95
  46.              Updated assignment constructor; added Preallocate() routine
  47.  
  48.         4/30/95
  49.              Made changes so the code is platform-independent (ANSI C++);
  50.              however, I have included a #define for Macintosh platforms
  51.              for speedier operations.
  52.  
  53.         11/22/95
  54.              Removed #define for Macintosh platforms - having this second
  55.              set of code made maintaining the class more of a chore than it
  56.              needed to be. True ANSI C++ compatibility except for the
  57.              Random() routine.
  58.              Changed code so the class is now a *template* class for
  59.              true multiple data type support. Yeah!
  60. */
  61.  
  62.  
  63. // ---------------------------------------------------------------------------
  64.  
  65. enum {
  66.     kDynamoArrayOutOfBoundsErr = -1        // Error code returned by the methods
  67. };
  68.  
  69. // ---------------------------------------------------------------------------
  70.  
  71. /*
  72.     IMPORTANT:
  73.     -----------
  74.     When using arrays, it is always tricky dealing with indices.
  75.     Remember that arrays start with 0, as in anArray[0]. This is different
  76.     from Pascal, where the first item starts at 1, as in anArray[1]. So in C and
  77.     C++ the correct boundaries are anArray[0] to anArray[x - 1], where x is the
  78.     number of items in the array. In Pascal this would be anArray[1] to
  79.     anArray[x].
  80.     
  81.     To clarify things, I use two terms: whole values and index values.
  82.     Whole values range from 1 to the number of items, and index values
  83.     range from 0 to the number of items - 1. So there. No reason for anyone
  84.     to get confused anymore, is there?
  85.     
  86.     Remember: index => 0 to n-1
  87.               whole => 1 to n
  88. */
  89.  
  90.  
  91. template <class DynamoArrayType>
  92. class DynamoArray {
  93.     public:
  94.         DynamoArray();
  95.         DynamoArray(short size);
  96.         ~DynamoArray();
  97.         
  98.         // Copy constructor
  99.         DynamoArray(DynamoArray& sourceArray);
  100.         
  101.         // Assignment operator
  102.         DynamoArray operator=(const DynamoArray& sourceArray);
  103.  
  104.         /*
  105.             [] operator
  106.             Bracket operator; pass a valid INDEX value (0 to fCurSize - 1).
  107.             (Note: fCurSize is the size of the array).
  108.         */
  109.         DynamoArrayType *operator[] (short index);
  110.  
  111.         /*
  112.             Preallocate.
  113.             Increases the size of the array to the specified length.
  114.             Note: old contents of array are destroyed and not saved.
  115.  
  116.             You may call this routine *before* adding any data to the
  117.             array if you know beforehand the approximate size of the
  118.             array (otherwise the array might get deleted and reallocated
  119.             to make room if the array is too small; calling this
  120.             prevents multiple deletions & allocations as you're
  121.             adding items to the array). Mostly used in conjunction
  122.             with the default constructor, which has no size arguments...
  123.         */
  124.         void Preallocate(short size);
  125.  
  126.         /*
  127.             SizeOf.
  128.             Get how many items are stored in array.
  129.             Returns a WHOLE value, from 1 to x.
  130.         */
  131.         virtual short SizeOf() { return fCurSize; }
  132.  
  133.         /*
  134.             Get.
  135.             Specify an INDEX number from 0 to fCurSize - 1. Returns
  136.             kDynamoArrayOutOfBoundsErr if the array is empty;
  137.             else the INDEX number of the item chosen.
  138.         */
  139.         virtual short Get(DynamoArrayType& theItem, short index);
  140.         
  141.         /*
  142.             RandomGet.
  143.             Get a random item from the array. The item is NOT deleted from
  144.             the array. Returns the INDEX value of the item randomly chosen,
  145.             kDynamoArrayOutOfBoundsErr (-1) if array is empty.
  146.         */
  147.         virtual short RandomGet(DynamoArrayType& theItem);
  148.         
  149.         /*
  150.             Append.
  151.             Inserts the specified item at the end of the array. Returns the
  152.             INDEX value of the inserted item.
  153.         */
  154.         virtual short Append(const DynamoArrayType& theItem);
  155.  
  156.         /*
  157.             Insert.
  158.             Inserts the specified item into the array at the specified
  159.             INDEX location. Valid locations are from 0 to fCurSize, not
  160.             just 0 to fCurSize - 1!
  161.             Using fCurSize as the location is essentially the same as Append().
  162.  
  163.             Returns kDynamoArrayOutOfBoundsErr if error occured and
  164.             unable to insert item; if able to insert item, returns
  165.             the INDEX item was inserted into.
  166.         */
  167.         virtual short Insert(const DynamoArrayType& theItem, short index);
  168.  
  169.         /*
  170.             Delete.
  171.             Delete the specified item at array INDEX.
  172.             Specify an item number from 0 to fCurSize - 1.
  173.             If the array is empty, Delete() returns kDynamoArrayOutOfBoundsErr;
  174.             else the INDEX value of the item deleted.
  175.         */
  176.         virtual short Delete(short index);
  177.  
  178.         /*
  179.             SearchDelete.
  180.             Remove the specified item in the array, if that item
  181.             exists. Basically a call to Search(item, x) and then calling Delete(x).
  182.             Returns kDynamoArrayOutOfBoundsErr if item not in array,
  183.             else the INDEX of the item deleted (from 0 to fCurSize - 1).
  184.         */
  185.         virtual short SearchDelete(DynamoArrayType& theItem, short startIndex = 0);
  186.         
  187.         /*
  188.             Remove.
  189.             Get the specified item from the array, and then delete that item.
  190.             Almost the same as calling Get(x) and then calling Delete(x).
  191.             However, you must pass to Remove the variable that is to hold the
  192.             deleted item. Item specified should be from 0 to fCurSize - 1.
  193.             Returns kDynamoArrayOutOfBoundsErr if the array is empty, else
  194.             the array INDEX of the item removed.
  195.         */
  196.         virtual short Remove(DynamoArrayType& theItem, short index);
  197.         
  198.         /*
  199.             RandomRemove.
  200.             Same as Remove(), except item removed is randomly chosen.
  201.         */
  202.         virtual short RandomRemove(DynamoArrayType& theItem);
  203.  
  204.         /*
  205.             Search.
  206.             Looks for specified item in the array.
  207.             Returns kDynamoArrayOutOfBoundsErr if not found, else INDEX of item.
  208.         */
  209.         virtual short Search(const DynamoArrayType& source, short startIndex = 0);
  210.  
  211.  
  212.     protected:
  213.         short fMaxSize;                // Real length of array    (it's maximum size).
  214.         short fCurSize;                // Number of items in array currently.
  215.         DynamoArrayType *fArray;    // The array itself (actually pointer to the array)
  216.  
  217.         unsigned short GetRandom(unsigned short min, unsigned short max);
  218.         void IncreaseSize();
  219. }; // END DynamoArray
  220.  
  221. // END Class_DynamoArray.h
  222.  
  223. #endif // CLASS_DYNAMOARRAY_H_